Interagir avec une boîte mail en Node.js avec ImapFlow et MailParser

Envoyer des emails avec Node.js, c’est très simple avec des outils comme Nodemailer !

Notre article dédié pour l’envoi d’email en Node.js

Mais il existe aussi beaucoup de cas où l’on veut faire l’inverse : lire les emails reçus.

Par exemple, pour traiter automatiquement des demandes entrantes, récupérer des pièces jointes, analyser des réponses clients, ou déclencher une action lorsqu’un message arrive dans une boîte spécifique.

Pour cela, on utilise généralement un protocol dédié : IMAP (Internet Message Access Protocol).

IMAP permet à une application de se connecter à une boîte mail pour lire, parcourir et manipuler les messages.

En Node.js, deux bibliothèques sont particulièrement pratiques pour ce besoin : ImapFlow et MailParser.

ImapFlow est un client IMAP moderne pour Node.js, avec une API basée sur les Promises et async/await (documentation officielle).

MailParser, de son côté, permet de transformer un email brut en objet JavaScript exploitable. Sa fonction simpleParser est pratique pour les cas simples, tandis que la classe MailParser permet de traiter les gros messages sous forme de streams (documentation officielle).

Fonctionnement

Installer les dépendances

On commence par installer les deux packages :

npm install imapflow mailparser

Si vous utilisez TypeScript, ImapFlow fournit déjà ses propres types. Pour MailParser, vous pouvez ajouter :

npm install -D @types/mailparser

Se connecter à une boîte mail

Voici un exemple avec Gmail, mais le principe est le même avec n’importe quel serveur IMAP.

import { ImapFlow } from "imapflow";

const client = new ImapFlow({
  host: "imap.gmail.com",
  port: 993,
  secure: true,
  auth: {
    user: "votre-adresse@gmail.com",
    pass: "votre-app-password",
  },
});

await client.connect();

Pour Gmail, il ne faut pas utiliser votre mot de passe principal.

Il faut générer un App Password depuis votre compte Google, puis l’utiliser comme mot de passe IMAP.

Lire les derniers emails

Une fois connecté, il faut ouvrir une boîte. La plus courante est INBOX.

const lock = await client.getMailboxLock("INBOX");

try {
  for await (const message of client.fetch("1:*", {
    envelope: true,
    source: true,
  })) {
    console.log(message.envelope.subject);
  }
} finally {
  lock.release();
}

Le lock évite que plusieurs opérations entrent en conflit sur la même boîte.

C’est une bonne habitude avec ImapFlow : on verrouille, on travaille, puis on libère.

Ici, source: true permet de récupérer l’email brut. C’est ce contenu que nous allons ensuite donner à MailParser.

Parser un email avec MailParser

Un email n’est pas un simple texte. Il peut contenir du HTML, du texte brut, des pièces jointes, des encodages différents, des headers, des destinataires, etc.

MailParser s’occupe de transformer tout cela en objet plus facile à manipuler :

import { simpleParser } from "mailparser";

for await (const message of client.fetch("1:*", {
  envelope: true,
  source: true,
})) {
  const parsed = await simpleParser(message.source);

  console.log({
    subject: parsed.subject,
    from: parsed.from?.text,
    text: parsed.text,
    html: parsed.html,
  });
}

simpleParser charge le message en mémoire.

C’est très pratique pour démarrer, mais si vous traitez de gros emails ou beaucoup de pièces jointes, il faudra plutôt utiliser l’API en streaming de MailParser.

Lire uniquement les emails non lus

Dans la vraie vie, vous ne voulez pas relire toute la boîte à chaque exécution.

Vous pouvez chercher uniquement les emails non lus :

for await (const message of client.fetch(
  { seen: false },
  { envelope: true, source: true }
)) {
  const parsed = await simpleParser(message.source);

  console.log(parsed.subject);
}

Ensuite, vous pouvez marquer le message comme lu :

await client.messageFlagsAdd(message.uid, ["\\Seen"], { uid: true });

Cela permet de construire facilement un petit worker qui traite seulement les nouveaux emails.

Exemple complet

import { ImapFlow } from "imapflow";
import { simpleParser } from "mailparser";

const client = new ImapFlow({
  host: "imap.gmail.com",
  port: 993,
  secure: true,
  auth: {
    user: process.env.MAIL_USER,
    pass: process.env.MAIL_PASSWORD,
  },
});

await client.connect();

const lock = await client.getMailboxLock("INBOX");

try {
  for await (const message of client.fetch(
    { seen: false },
    { uid: true, source: true }
  )) {
    const parsed = await simpleParser(message.source);

    console.log("Sujet :", parsed.subject);
    console.log("De :", parsed.from?.text);
    console.log("Texte :", parsed.text);

    await client.messageFlagsAdd(message.uid, ["\\Seen"], { uid: true });
  }
} finally {
  lock.release();
  await client.logout();
}